.\" MinTTY man page
.\"
.\" This 'man' page is Copyright 2009 (c) Andy Koppe and Lee D. Rothstein
.\"
.\" You may distribute, use, and modify this man page under the terms
.\" of the GNU Free Documentation License (GFDL), Version 1.3,
.\" 3 November 2008 (or later) as specified.
.ad l
.TH mintty 1 2009-07-18 0.4.4 Cygwin

.SH NAME

mintty - Cygwin terminal emulator


.SH SYNOPSIS

\fBmintty\fP [\fIOPTION\fP]... [ \fB-\fP | \fIPROGRAM\fP [\fIARG\fP]... ]


.SH DESCRIPTION

\fBMinTTY\fP is a terminal emulator for Cygwin with a native Windows user
interface and minimalist design.
Its terminal emulation is largely compatible with \fBxterm\fP, but it does not
require an X server to be running.


.SH INVOCATION

If a program name is supplied on the command line, this is executed with any
additional arguments passed to it.
Otherwise, MinTTY looks for a shell to execute in the \fISHELL\fP environment
variable.
If that is not set, it tries to read the user's default shell setting from
\fI/etc/passwd\fP.
Finally, it falls back to \fI/bin/sh\fP.
If a single dash is specified instead of a program name, the shell is invoked
as a login shell.


.SH OPTIONS

MinTTY accepts the standard GNU option formats, with single dashes
introducing short options and double dashes introducing long options,
e.g. \fB-o arg\fP, \fB--option arg\fP, and \fB--option=arg\fP.

.TP
\fB-e\fP, \fB--exec\fP \fIPROGRAM\fP [\fIARG\fP ...]
Execute the specified program in the terminal session and pass on any additional
arguments.
This option can be omitted, in which case the first non-option argument, if any,
is taken as the name of the program to execute.

.TP
\fB-c\fP, \fB--config\fP=\fIFILENAME\fP
Use the specified configuration file instead of the default \fI~/.minttyrc\fP.

.TP
\fB-p\fP, \fB--position\fP=\fIX\fB,\fIY\fR
Open the window with its top left corner at the specified coordinates.

.TP
\fB-s\fP, \fB--size\fP=\fICOLS\fB,\fIROWS\fR
Set the default numbers of terminal columns and rows.

.TP
\fB-t\fP, \fB--title\fP=\fITITLE\fP
Use \fITITLE\fP as the initial window title.
By default, the title is set to the executed command.

.TP
\fB-i\fP, \fB--icon\fP=\fIFILE\fP
Load the window icon from a Windows \fI.ICO\fP file.

.TP
\fB-l\fP, \fB--log\fP=\fIFILE\fP
Copy all output into the specified log file.

.TP
\fB-u\fP, \fB--utmp\fP
Create a utmp entry.

.TP
\fB-h\fP, \fB--hold\fP=\fBnever\fP|\fBalways\fP|\fBerror\fP
Determine whether to keep the terminal window open when the command exits.
The argument can be abbreviated to a single letter.
By default, the window is closed immediately.
Alternatively, it can be set to always stay open, or to stay open only if
the command finished with a non-zero exit code or due to a runtime error signal.

.TP
\fB-H\fP, \fB--help\fP
Display a brief help message and exit.

.TP
\fB-V\fP, \fB--version\fP
Print version information and exit.


.SH USAGE

MinTTY aims to adhere to both Windows and Unix conventions usage.
Where they conflict, the Windows conventions take precedence,
at least in the default configuration.

.SS Menu

MinTTY's context menu can be opened by right-clicking the mouse or by pressing
the \fBMenu\fP key that is normally located next to the right Ctrl key.


.SS Options dialog

The configuration can be changed in a graphical dialog, which can be opened by
selecting \fBOptions...\fP in MinTTY's context menu or window menu.
(The window menu can be opened by clicking on the program icon in the title or
by pressing \fBAlt+Space\fP.)
See the \fBCONFIGURATION\fP section for details.


.SS Copy & paste

As usual in Windows, screen contents can be selected by holding
down the left mouse button and dragging the mouse.
The selection can be extended by holding down \fBShift\fP or \fBCtrl\fP while
left-clicking.
Double-clicking or triple-clicking selects a whole word or line.

In the default configuration, selected text has to be explicitly copied
to the clipboard using either the \fBCopy\fP menu command, the
\fBCtrl+Ins\fP keyboard shortcut, or the middle mouse button combined
with \fBShift\fP.
(See the \fBCopy on select\fP setting for X-like copy behaviour.)

The selected region is copied as "rich text" as well as normal text,
which means it can be pasted with colours and formatting into applications
that support it, e.g. word processors.

The clipboard contents can be pasted using either the \fBPaste\fP menu command,
the \fBShift+Ins\fP keyboard shortcut, or the middle mouse button.
Not only text but also files and directories can be pasted,
whereby the latter are inserted as quoted filenames.


.SS Drag & drop

Text, files and directories can also be dropped into the MinTTY window.


.SS Font zoom

The font size can be increased or decreased using the keyboard shortcuts
\fBCtrl+plus\fP and \fBCtrl+minus\fP.
\fBCtrl+zero\fP returns it to the size configured in the options dialog.


.SS Fullscreen

Fullscreen mode can be toggled using either the \fBFullscreen\fP command in
the menu or the \fBAlt+F11\fP keyboard shortcut.


.SS Default size

If the window has been resized, it can be returned to the default size set in
the Window panel of the options using the \fBDefault size\fP command in the menu
or the \fBAlt+F10\fP shortcut.


.SS Scrolling

MinTTY has a scrollback buffer that can hold up to 10000 lines in the default
configuration.
It can be accessed using the scrollbar, the mouse wheel, or the keyboard.
Hold the \fBShift\fP key while pressing the \fBUp\fP and \fBDown\fP arrow keys
to scroll line-by-line or the \fBPageUp\fP and \fBPageDown\fP keys to scroll
page-by-page.
The modifier key for scrolling can be changed in the options dialog.

Scrolling into the scrollback buffer is not available with programs such
as pagers or editors that use the the terminal's "alternate screen".


.SS AltGr

The \fBAltGr\fP key on non-US keyboards has the same effect as if both
\fBCtrl\fP and \fBAlt\fP are held.


.SS Mouse tracking

When an application activates mouse tracking, mouse events are sent to the
application rather than processed by MinTTY.
This is indicated by the mouse pointer changing from an I shape to an arrow.
Holding down \fBShift\fP overrides mouse tracking mode and sends mouse
events to MinTTY instead, so that e.g. text can be selected and the menu
can be accessed.
(The modifier key for overriding mouse tracking can be changed in the
options dialog.)


.SS TERM variable

The \fITERM\fP variable for the child process is set to "xterm", so that
programs that pay attention to it expect xterm keycodes and output
xterm-compatible control sequences.


.SH CONFIGURATION

Most MinTTY settings are chosen not through command line arguments but in its
graphical options dialog, which can be reached via the context menu or
the window menu.
Settings are stored in a configuration file that by default is located
at \fI~/.minttyrc\fP.
This can be overridden with the \fB--config\fP command line option.
Settings are written to the file whenever the \fBOK\fP button is pressed in
the options dialog.

The following sections explain the settings on each pane of the options
dialog.
For each setting, its name in the config file is shown in parentheses,
along with its default value, e.g. Columns=80.
For multiple-choice settings, the value representing each choice in the config
file is shown.


.SS Window
Window properties.

.TP
\fBColumns\fP (Columns=80)
Default width of the window, in character cells.

.TP
\fBRows\fP (Rows=24)
Default height of the window, in character cells.

.TP
\fBCurrent size\fP
Pressing this button sets the default width and height of the window to
its current size.

.TP
\fBDisplay scrollbar\fP (Scrollbar=1)
Show the scrollbar for accessing the scrollback buffer on the right of the
window.

.TP
\fBConfirm exit\fP (ConfirmExit=1)
If enabled, ask for confirmation when the close button or \fIAlt+F4\fP is 
pressed and the command running in MinTTY has any child processes.

.TP
\fBScrollback lines\fP (ScrollbackLines=10000)
The maximum number of lines to keep in the scrollback buffer.

.TP
\fBModifier for scrolling with cursor keys\fP (ScrollMod=1)
The modifier key that needs to be pressed together with the arrow up/down
or page up/down keys to access the scrollback buffer.
The default is \fBShift\fP.
Scrolling with cursor keys can also be disabled here.

.RS
.PD 0
.IP "\- \fBShift\fP (1)"
.IP "\- \fBCtrl\fP (4)"
.IP "\- \fBAlt\fP (2)"
.IP "\- \fBOff\fP (0)"
.RE


.SS Looks
Settings affecting MinTTY's appearance.

.TP
\fBColours\fP
Clicking on one of the buttons here opens the colour selection dialog.
In the config file, colours are represented as comma-separated RGB triples
with decimal 8-bit values (i.e. ranging from 0 to 255).

.RS
.PD 0
.IP "\- \fBForeground\fP (ForegroundColour=191,191,191)
.IP "\- \fBBackground\fP (BackgroundColour=0,0,0)
.IP "\- \fBCursor\fP (CursorColour=191,191,191)
.RE

.TP
\fBTransparency\fP (Transparency=0)
Window transparency level, with the following choices:

.RS
.PD 0
.IP "\- \fBOff\fP (0)"
.IP "\- \fBLow\fP (1)"
.IP "\- \fBMedium\fP (2)"
.IP "\- \fBHigh\fP (3)"
.RE

.TP
\fBOpaque when focused\fP (OpaqueWhenFocused=0)
Enable to make the window opaque when it is active (to avoid background
distractions when working in it).

.TP
\fBCursor\fP (CursorType=2)
The following cursor types are available:

.RS
.PD 0
.IP "\- \fBBlock\fP (0)"
.IP "\- \fBUnderscore\fP (1)"
.IP "\- \fBLine\fP (2)"
.RE

.TP
\fBEnable cursor blinking\fP (CursorBlinks=1)
If enabled, the cursor blinks at the rate set in Windows' keyboard control
panel.


.SS Text
Settings controlling text display.

.TP
\fBFont...\fP
Clicking on this button opens the font dialog, where the font and its
properties can be chosen.
In the config file, this corresponds to the following entries:

.RS
.PD 0
.IP "\- \fBFont\fP (Font=Lucida Console)"
.IP "\- \fBSize\fP (FontHeight=10)"
.IP "\- \fBStyle\fP (FontIsBold=0)"
.IP "\- \fBScript\fP (FontCharset=0)"
.RE

.TP
\fBSmoothing\fP (FontQuality=0)
Select the type of font smoothing, if any, from the following choices:

.RS
.PD 0
.IP "\- \fBSystem Default\fP (0)"
.IP "\- \fBAntialiased\fP (1)"
.IP "\- \fBNone\fP (2)"
.IP "\- \fBClearType\fP (3)"
.RE

.TP
\fBShow bold as bright\fP (BoldAsBright=1)
If selected, text with the ANSI bold attribute set is displayed with
increased brightness.
Otherwise, it is shown with a bold font, which tends to look better with
black-on-white text.

.TP
\fBAllow blinking\fP (AllowBlinking=0)
ANSI text blinking is diabled by default, on the grounds that blinking
text is a crime against aesthetic decency.

.TP
\fBCodepage\fP (Codepage=ISO-8859-1:1998 (Latin-1, West Europe))
The codepage used for encoding input and decoding output.
Select \fBUTF-8\fP for 8-bit Unicode.


.SS Keys
Settings controlling keyboard behaviour.

.TP
\fBEscape keycode\fP (EscapeSendsFS=0)
The character to be sent by the escape key.
The default is the standard escape character \fB^[\fP, but the character
\fB^\\\fP can be used instead, thereby allowing the escape key to be used as
one of the special keys in the terminal line settings (see stty(1)).
This is impractical with \fB^[\fP, as that appears as the first character in
multi-character keycodes.

.RS
.PD 0
.IP "\- \fB^[\fP (0)"
.IP "\- \fB^\(rs\fP (1)"
.RE

.TP
\fBBackspace keycode\fP (BackspaceSendsDEL=0)
The character to be sent by the backspace key.
The default is \fB^H\fP, because that is the default across Cygwin,
but \fB^?\fP (DEL) can be used instead to free up Ctrl+H for other
purposes, e.g. as the help key in Emacs.

.RS
.PD 0
.IP "\- \fB^H\fP (0)"
.IP "\- \fB^?\fP (1)"
.RE

.TP
\fBAlt key on its own sends ^[\fP (AltSendsESC=0)
The Alt key pressed on its own can be set to send the escape character
\fB^[\fP.
This can save the regular trip to the upper left corner of the keyboard
for \fIvi\fP users, and can also be useful when the escape key is set to send
\fB^\\\fP instead.

.TP
\fBWindow command shortcuts\fP (WindowShortcuts=1)
Checkbox for enabling window command shortcuts.
When disabled, these combinations send their regular keycodes to the
application.

.RS
.PD 0
.IP "\- \fBAlt+Space\fP: Menu"
.IP "\- \fBAlt+F2\fP: Duplicate"
.IP "\- \fBAlt+F4\fP: Close"
.IP "\- \fBAlt+F10\fP: Default size"
.IP "\- \fBAlt+F11\fP or \fBAlt+Enter\fP: Fullscreen"
.RE

.TP
\fBCopy and paste shortcuts\fP (EditShortcuts=1)
Checkbox for enabling the copy and paste shortcuts.

.RS
.PD 0
.IP "\- \fBCtrl+Ins\fP: Copy"
.IP "\- \fBShift+Ins\fP: Paste"
.RE

.TP
\fBZoom shortcuts\fP (ZoomShortcuts=1)
Checkbox for enabling font zoom shortcuts.

.RS
.PD 0
.IP "\- \fBCtrl+plus\fP: Zoom in"
.IP "\- \fBCtrl+minus\fP: Zoom out"
.IP "\- \fBCtrl+zero\fP: Reset zoom to configured font size"
.RE


.SS Mouse
Settings controlling mouse support.

.TP
\fBRight click action\fP (RightClickAction=0)
Action to take when clicking the right mouse button.

.RS
.PD 0
.IP "\- \fBShow menu\fP (0): Display the context menu.
.IP "\- \fBExtend\fP (1): Extend the selected region.
.IP "\- \fBPaste\fP (2): Paste the clipboard contents.
.RE

.TP
\fBCopy on select\fP (CopyOnSelect=0)
If enabled, the region selected with the mouse is copied to the clipboard as
soon as the mouse button is released, thus emulating X Window behaviour.

.TP
\fBClicks place cursor\fP (ClicksPlaceCursor=0)
If enabled, the command line cursor can be placed by pressing the left
mouse button.
This works by sending the number of cursor keycodes needed to get to the
destination.

.TP
\fBDefault click target\fP (ClicksTargetApp=1)
This applies to application mouse mode, i.e. when the application activates
xterm-style mouse reporting.
In that mode, mouse clicks can be sent either to the application to process,
or to the window for the usual actions: select, extend, paste, show menu.

.RS
.PD 0
.IP "\- \fBWindow\fP (0)
.IP "\- \fBApplication\fP (1)
.RE

.TP
\fBModifier key for overriding default\fP (ClickTargetMod=1)
The modifier key selected here can be used to override the default click
target in application mouse mode.
Overriding can also be disabled.
With the default settings, clicks are sent to the application,
and Shift has to be pressed while clicking in order to trigger window actions
instead.

.RS
.PD 0
.IP "\- \fBShift\fP (1)"
.IP "\- \fBCtrl\fP (4)"
.IP "\- \fBAlt\fP (2)"
.IP "\- \fBOff\fP (0)"
.RE


.SS Output
Settings for output devices other than the terminal screen.

.TP
\fBPrinter\fP (Printer=)
The ANSI standard defines control sequences for sending text to a printer,
which are used by some terminal applications such as the mail reader
\fBpine\fP.
The Windows printer to send such text to can be selected here.
By default, printing is disabled.

.TP
\fBBell action\fP (BellType=1)
The action to take when the application sends the bell character \fB^G\fP.

.RS
.PD 0
.IP "\- \fBNone\fP (0)"
.IP "\- \fBSystem sound\fP (1)"
.IP "\- \fBFlash window\fP (2)"
.RE


.SH KEYCODES

For alphanumeric and symbol keys MinTTY uses the Windows keyboard layout 
to translate key presses into characters, which means that the keyboard layout
can be switched using the standard Windows mechanisms for that purpose.
\fBAltGr\fP combinations, dead keys, and input method editors (IMEs) are all
supported.

The Windows keyboard layout yields Unicode codepoints, which are encoded
using the \fBCodepage\fP selected in MinTTY's configuration before sending them
to the application.
(The UTF-8 codepage can be selected for full Unicode input support.)

Should the available keyboard layouts lack required features,
Microsoft's \fBKeyboard Layout Creator\fP (MSKLC), available from
\fIhttp://www.microsoft.com/Globaldev/tools/msklc.mspx\fP,
can be used to create custom keyboard layouts.

For other keys, MinTTY sends xterm keycodes as described at
\fIhttp://invisible-island.net/xterm/ctlseqs/ctlseqs.html\fP, with a few
minor changes and additions.

Caret notation is used to show control characters.
See \fIhttp://en.wikipedia.org/wiki/Caret_notation\fP for an explanation.


.SS Alt and Meta

As is customary with PC keyboards, the \fBAlt\fP key acts as the so-called
\fBMeta\fP modifier.
When it is held down while pressing a key or key combination, the keycode is
prepended with the escape character \fB^[\fP, unless noted otherwise in
the keycode tables in the following sections.

Encoding the meta modifier by setting the top bit of a character instead
of prefixing it with the escape character is not supported, because that
does not work for characters beyond 7-bit ASCII.


.SS Letter keys

If the Windows keyboard layout does not have a keycode for a letter key press
and the \fBCtrl\fP key is down, MinTTY sends a control character.
The character sent corresponds to the key's "virtual keycode".
For keyboards with Latin scripts the virtual keycodes reflect the keys' labels,
whereas for others, the virtual keys are usually laid out the same as on the US
keyboard.

.RS
.TS
tab(#) nospaces;
LI    LB    LB
LB    LfC   LfC.
Key  #Ctrl #Ctrl+Alt
A    #^A   #^[^A
B    #^B   #^[^B
\fP...
Z    #^Z   #^[^Z
.TE
.RE

.SS Number and symbol keys

In the same way as for letter keys, the Windows keyboard layout is consulted
first for number and symbol keys.


.SS Control keys

The keys here send the usual control characters, but there are a few
MinTTY-specific additions that make combinations with modifier keys
available as separate keycodes.

.RS
.TS
tab(#) nospaces;
LI        s     LB    LB    LB    LB    LB
LB        LfC   LfC   LfC   LfC   LfC   LfC.
Key            #Shift#Crtl #C+S   #Alt  #A+S
Space    #\fISP#\fISP#^@   #^[^@  #^[\fISP#^[\fISP
Enter    #^M   #^J   #^^   #^[^^  #^[^M #^[J
Back (^H)#^H   #^H   #^?   #^[^?  #^[^H #^[^H
Back (^?)#^?   #^?   #^_   #^[^_  #^[^? #^[^?
Tab      #^I   #^[[Z #^[[1;5I#^[[1;6I
Pause    #^]
Break    #^\(rs
.TE
.RE

The \fBBack\fP and \fBEsc\fP keycodes can be configured in the options dialog,
which is why different keycodes depending on those settings are shown.
On most keyboards \fBPause\fP and \fBBreak\fP share a key, whereby \fBCtrl\fP
has to be pressed to get the \fBBreak\fP function.


.SS Modifier Keys

The remaining keys all use a common encoding for modifier keys.
When one or more of the following modifier keys are pressed,
they are encoded by adding the associated value to 1.

.RS
.PD 0
.IP "\- \fBShift\fP: 1
.IP "\- \fBAlt  \fP: 2
.IP "\- \fBCtrl \fP: 4
.RE

For example, \fBShift+Ctrl\fP would be encoded as the character \fB6\fP (i.e. 1+1+4).
The modifier code is shown as \fIm\fP in the following sections.


.SS Cursor keys

Cursor keycodes without modifier keys depend on the terminal's 
"application cursor mode", which is used by fullscreen applications such as
editors and pagers.
When one or more modifier keys are pressed, the application cursor mode is
ignored, but the modifier code is inserted into the keycode as shown.
The \fBHome\fP and \fBEnd\fP keys are considered cursor keys.

.RS
.TS
tab(#) nospaces;
LI    s     LB    LB
LB    LfC   LfC   LfC.
Key        #app  #modified
Up   #^[[A #^[OA #^[[1;\fIm\fPA
Down #^[[B #^[OB #^[[1;\fIm\fPB
Left #^[[D #^[OD #^[[1;\fIm\fPD
Right#^[[C #^[OC #^[[1;\fIm\fPC
Home #^[[H #^[OH #^[[1;\fIm\fPH
End  #^[[F #^[OF #^[[1;\fIm\fPF
.TE
.RE


.SS Editing keys

There is no special application mode for the editing keys in the block of six
that is usually situated above the cursor keys, but modifiers can be applied.

.RS
.TS
tab(#) nospaces;
LI     s     LB
LB     LfC   LfC.
Key         #modified
Ins   #^[[2~#^[[2;\fIm\fP~
Del   #^[[3~#^[[3;\fIm\fP~
PgUp  #^[[5~#^[[5;\fIm\fP~
PgDn  #^[[6~#^[[6;\fIm\fP~
.TE
.RE


.SS Function keys

\fBF1\fP through \fBF4\fP send numpad-style keycodes, because they
emulate the four PF keys above the number pad on the VT100 terminal.
The remaining function keys send codes that were introduced with
the VT220 terminal.

.RS
.TS
tab(#) nospaces;
LI  s      LB
LB  LfC    LfC.
Key       #modified
F1 #^[OP  #^[[1;\fIm\fPP
F2 #^[OQ  #^[[1;\fIm\fPQ
F3 #^[OR  #^[[1;\fIm\fPR
F4 #^[OS  #^[[1;\fIm\fPS
F5 #^[[15~#^[[15;\fIm\fP~
F6 #^[[17~#^[[17;\fIm\fP~
F7 #^[[18~#^[[18;\fIm\fP~
F8 #^[[19~#^[[19;\fIm\fP~
F9 #^[[20~#^[[20;\fIm\fP~
F10#^[[21~#^[[21;\fIm\fP~
F11#^[[23~#^[[23;\fIm\fP~
F12#^[[24~#^[[24;\fIm\fP~
.TE
.RE


.SS Alt+Numpad

MinTTY supports the Alt+Numpad method for entering character codes, whereby
the \fBAlt\fP key has to be held while entering the character's Unicode
codepoint.
If the first digit entered is a zero, the codepoint is interpreted as octal,
otherwise as decimal.
The codepoint is encoded using the selected codepage before it is sent.


.SS Mousewheel

In xterm mouse reporting modes, the mousewheel is treated is a pair of mouse
buttons.
However, the mousewheel can also be used for scrolling in applications such as
\fIless\fP that do not support xterm mouse reporting but that do use the
alternate screen.
Under those circumstances, mousewheel events are
encoded as follows:

.RS
.TS
tab(#);
LB LfC.
line up#^[Oa
line down#^[Ob
page up#^[[1;2a
page down#^[[1;2b
.TE
.RE

The number of line up/down events sent per mousewheel notch depends on
the relevant Windows setting on the \fBWheel\fP tab of the \fBMouse\fP
control panel.
Page up/down codes can be sent by holding down \fBShift\fP while scrolling.
The Windows wheel setting can also be set to always scroll by a whole screen
at a time.


.SH CONTROL SEQUENCES

MinTTY supports most of the xterm control sequences documented at \fIhttp://invisible-island.net/xterm/ctlseqs/ctlseqs.html\fP.
Please report incompatibilities or unimplemented sequences as bugs.

Below are MinTTY control sequences not currently supported in xterm.


.SS Cursor style

The VT510 DECCSUSR sequence can be used to control cursor shape and blinking.

.RS
\fC^[[ \fIarg\fC \fISP\fC q\fR

.TS
tab(#) nospaces;
LI  LB         LB
LfC L          L.
arg#shape     #blinking
0  #default   #default
1  #block     #yes
2  #block     #no
3  #underscore#yes
4  #underscore#no
5  #line      #yes
6  #line      #no
.TE
.RE


.SS Escape key mode

In application escape key mode, the escape key sends a keycode that allows
applications to tell it apart from the escape character appearing at the start
of many other keycodes, without resorting to a timeout mechanism.

.RS
.TS
tab(#) nospaces;
LB        LB          LB
LfC       L           LfC.
sequence #mode       #keycode
^[[?7727l#normal     #^[
^[[?7727h#application#^[O[
.TE
.RE


.SS Ambiguous width reporting

Applications can ask to be notified when the width of the so-called
"ambiguous width" character category changes due to the user changing font.

.RS
.TS
tab(#) nospaces;
LB        LB
LfC       L.
sequence #reporting
^[[?7700l#disabled
^[[?7700h#enabled
.TE
.RE

When enabled, '\fC^[[1W\fP' is sent when changing to an "ambiguous narrow"
font and '\fC^[[2W\fP' is sent when changing to an "ambiguous wide" font.


.SH TIPS

A few tips on setting up MinTTY and other programs.


.SS Shortcuts

The mintty Cygwin package installs a shortcut in the Windows start menu
under \fIAll Programs/Cygwin\fP.
It starts mintty with a '-' as its only argument, which tells it to invoke
the user's default shell as a login shell.

Shortcuts are also a convenient way to start MinTTY with additional options
and different commands.
For example, shortcuts for access to remote machines can be created by
invoking \fIssh\fP.
The command simply needs to be appended to the target field of the shortcut
(in the shortcut's properties):

.RS
Target:  \fCC:\\Cygwin\\bin\\mintty.exe \f(CBssh server\fR
.RE

The working directory for the session can be set in the "Start In:" field.
(But note that the bash login profile cd's to the user's home directory.)
Another convenient feature of shortcuts is the ability to assign global
shortcut keys.

Cygwin provides the \fBmkshortcut\fP utility for creating shortcuts from the
command line.
See its manual page for details.


.SS Starting mintty from folder context menus

Cygwin's \fBchere\fP package can be used to create a folder context menu
item for mintty in Windows Explorer.
This allows one to right click on a
folder and open a shell in that folder.

The following command will create a "Bash Prompt Here" for the current user.
See \fIchere\fP(1) for all the options.

.RS
\fCchere -i -c -t mintty\fP
.RE


.SS Starting mintty from a batch file

In order to start MinTTY from a batch file it needs to be invoked through the
\fIstart\fP command.
This avoids the batch file's console window staying open while MinTTY is
running.
For example:

.RS
\fCstart mintty -\fP
.RE


.SS Environment variables

Unfortunately Windows shortcuts do not allow the setting of environment
variables.
Variables can be set globally though via a button on the
\fBAdvanced\fP tab of the \fBSystem Properties\fP.
Those can be reached by right-clicking on \fBComputer\fP, selecting
\fBProperties\fP, then \fBAdvanced System Settings\fP.

Alternatively, global variables can be set using the \fIsetx\fP command
line utility.
This comes pre-installed with some versions of Windows but is also available 
as part of the freely downloadable \fBWindows 2003 Resource Kit Tools\fP.

Another way to set variables for the program to be run in \fBMinTTY\fP is by
invoking it through the \fBenv\fP command, e.g.:

.RS
\fCmintty env DISPLAY=:0 ssh -X server\fP
.RE


.SS The CYGWIN variable

The \fBCYGWIN\fP environment variable is used to control a number of settings
for the Cygwin runtime system.
Many of them apply to the Cygwin console only, but others can be useful
with any Cygwin process.
See \fIhttp://www.cygwin.com/cygwin-ug-net/using-cygwinenv.html\fP for details.


.SS Detecting MinTTY

MinTTY sets the \fITERM\fP variable to \fBxterm\fP for compatibility reasons,
but that of course makes it difficult to tell MinTTY apart from \fBxterm\fP when
required for example in shell startup scripts.

One way around that is to invoke the shell through the \fBenv\fP command to set
the \fITERM\fP variable differently:

.RS
\fCmintty env TERM=mintty bash -l\fP
.RE

This can then be tested for in a startup script to trigger MinTTY-specific
actions, followed by setting \fITERM\fP back to \fBxterm\fP.


.SS Changing the ANSI colours

A number of settings can be controlled through terminal control sequences,
including the colour values for the 16 ANSI colours.
Here is the xterm sequence for this, whereby \fInum\fP stands for the ANSI
number and \fIrrggbb\fP stands for a hexadecimal RGB colour value.

.RS
\fC^[]4;\fInum\fP;#\fIrrggbb\fP^G\fR
.RE

The \fB-e\fP option to the \fBecho\fP command is useful for emitting
control sequences.
For example, to turn yellow (colour 3) up to its full brightness:

.RS
\fCecho -e "\\e]4;3;#FFFF00\\a"\fP
.RE

Sequences such as this can be included in scripts or on the \fBmintty\fP
command line with the help of \fBsh -c\fP.


.SS Terminal line settings

Terminal line settings can be viewed or changed with the \fBstty\fP utility,
which is installed as part of Cygwin's core utilities package.
Among other things, it can set the control characters used for generating
signals or editing an input line.

See the \fBstty\fP man page for all the details, but here are a few examples.
The commands can be included in shell startup files to make them permanent.

To change the key for deleting a whole word from \fBCtrl+W\fP to
\fBCtrl+Backspace\fP (assuming the \fBBackspace\fP keycode is set to \fB^H\fP):

.RS
.nf
\fCstty werase '^?'\fP
.fi
.RE

To use \fBCtrl+Enter\fP instead of \fBCtrl+D\fP for end of file:

.RS
.nf
\fCstty eof '^^'\fP
.fi
.RE

To use \fBPause\fP and \fBBreak\fP instead of \fBCtrl+Z\fP and \fBCtrl+C\fP for
suspending or interrupting a process, and to also disable the
stackdump-producing SIGQUIT:

.RS
.nf
\fCstty susp '^]' swtch '^]' intr '^\' quit '^-'\fP
.fi
.RE

With these settings, the \fBEsc\fP key can also be used to interrupt
processes by setting its keycode to \fB^\\\fP.
The standard escape character \fB^[\fP cannot be used for that purpose
because it appears as the first character in many other keycodes.


.SS Readline configuration

Keyboard input for the \fBbash\fP shell and other program that use the
\fBreadline\fP library can be configured with the so-called
\fIinputrc\fP file.
Unless overridden by setting the \fIINPUTRC\fP variable, this is located
at \fI~/.inputrc\fP.

It consists of bindings of keycodes to readline commands, whereby
comments start with a hash character.
The file format is explained fully in the bash manual.

Anyone used to Windows key combinations for editing text might find the
following bindings useful:

.RS
.nf
\fC
# Ctrl+Left/Right to move by whole words
"\\e[1;5D": backward-word
"\\e[1;5C": forward-word

# Ctrl+Backspace/Delete to delete whole words
"\\d": backward-kill-word
"\\e[3;5~": kill-word

# Ctrl+Shift+Backspace/Delete to delete to start/end of the line
"\\e\\d": backward-kill-line
"\\e[3;6~": kill-line

# Alt-Backspace for undo
"\\e\\b": undo
\fP
.fi
.RE

Finally, a couple of bindings for convenient searching of the command history.
Just enter the first few characters of a previous command and press
\fBCtrl-Up\fP to look it up.

.RS
.nf
\fC
# Ctrl-Up/Down for searching command history
"\\e[1;5A": history-search-backward
"\\e[1;5B": history-search-forward
\fP
.fi
.RE


.SS Enabling non-ASCII input in bash and readline

By default, \fBreadline\fP treats the uppermost bit of input and output 
characters as the "meta" flag.
The following settings in \fI~/.inputrc\fP will disable that and thereby 
allow the use of characters outside the 7-bit ASCII character set:

.RS
.nf
\fC
set input-meta on
set convert-meta off
set output-meta on
\fP
.fi
.RE


.SS Mousewheel scrolling for less

No, this is not some sort of special offer, but a tip on how to enable
mousewheel scrolling in the pager program \fBless\fP.

Key bindings for \fBless\fP can be specified in the text file \fI~/.lesskey\fP.
Before the bindings can be used, they have be translated into
the binary file \fI~/.less\fP using the \fBlesskey\fP tool (which probably
saves about 0.0042 seconds when starting \fBless\fP).
See \fBlesskey\fP(1) for details.

Here are the lesskey lines needed for mousewheel support, assuming the
scroll modifier key is set to the default \fIShift\fP.
For \fBAlt\fP or \fBCtrl\fP, replace the \fB2\fPs in the keycodes with
\fB3\fPs or \fB5\fPs.

.RS
.nf
\fC
\\eOa back-line
\\eOb forw-line
\\e[1;2a back-screen
\\e[1;2b forw-screen
\fP
.fi
.RE


.SS Mode-dependent cursor in vim

Using the control sequences for cursor style and application escape key mode,
the \fBvim\fP editor can be configured to change cursor depending on mode.
For example, with the following lines in \fI.vimrc\fP, vim will show a block
cursor in normal mode and a line cursor in insert mode:

.RS
.nf
\fC
let &t_ti.="\\e[1 q\\e[?7727h"
let &t_SI.="\\e[5 q"
let &t_EI.="\\e[1 q"
let &t_te.="\\e[0 q\\e[?7727l"
noremap <Esc>O[ <Esc>
noremap! <Esc>O[ <Esc>
\fP
.fi
.RE

Without application escape key mode, it would take a second for the cursor to
change after pressing Esc to leave insert mode.
(That time can otherwise be reduced using vim's \fIttimeoutlen\fP setting,
at the risk of keycodes not being recognised in some circumstances.)


.SH LIMITATIONS

.SS Console Issue

MinTTY is not a complete replacement for the \fBCygwin\fP console,
which is based on the Windows command prompt (\fIcmd.exe\fP).
Like xterm and rxvt, MinTTY communicates with the child process through a
pseudo terminal device, which Cygwin emulates using Windows pipes.
This means that native Windows command line programs started in MinTTY see
a pipe rather than a console device.
As a consequence, interactive input often does not work correctly, and
direct calls to Win32 console functions will fail.
Programs that only output text are usually fine though.


.SS Termcap/terminfo

MinTTY does not have its own \fItermcap\fP or \fIterminfo\fP entries;
instead, it simply pretends to be an xterm.


.SS Missing xterm features

MinTTY is nowhere near as configurable as xterm, and its keycodes
are fixed according to xterm's PC-style keyboard behaviour (albeit
with a number of MinTTY-specific extensions).
Neither Tektronix 4014 emulation nor mouse highlighting mode are supported.


.SH SEE ALSO

\fIbash\fP(1), \fIenv\fP(1), \fIecho\fP(1), \fIstty(1)\fP,
\fImkshortcut\fP(1), \fIchere\fP(1), \fIlesskey\fP(1), vim(1)

\fIhttp://invisible-island.net/xterm/ctlseqs/ctlseqs.html\fP

\fIhttp://vt100.net/\fP


.SH ACKNOWLEDGEMENTS

MinTTY is based on PuTTY version 0.60 by Simon Tatham and contributors,
so big thanks to everyone involved.
Thanks also to KDE's Oxygen team for the program icon.


.SH COPYRIGHT

Copyright (C) 2008-09 Andy Koppe.

MinTTY is released under the terms of the the \fIGNU General Public License\fP
version 3 or later.
See \fIhttp://gnu.org/licenses/gpl/html\fP for the license text.

There is NO WARRANTY, to the extent permitted by law.


.SH CONTACT

Please report bugs or suggest enhancements via the MinTTY issue tracker at
\fIhttp://mintty.googlecode.com/issues\fP.
Questions can be directed to the MinTTY discussion group at
\fIhttp://groups.google.com/group/mintty-discuss\fP or
the Cygwin mailing list at \fIcygwin@cygwin.com\fP.


.SH AUTHOR

This manual page was written by Andy Koppe with much appreciated help
from Lee D. Rothstein.
